Copyright: Windows NT 3.51


Purpose and Background

The Microsoft® Win32® Internet functions for Win32 provide Win32 applications with easy access to common Internet protocols. These functions convert the Gopher, FTP (File Transfer Protocol), and HTTP (HyperText Transfer Protocol) protocols into task-focused interfaces which expand and extend use of the Internet.

The Win32 Internet functions are exported from the wininet.dll. Initially, the functions will be shipped independent of operating systems through the Microsoft Developer Network (MSDN), Compuserve, and the Internet. Independent service vendors (ISVs) may redistribute wininet.dll with their applications, following the model of Win32s. In the future, the functions described in this specification will be folded into all Microsoft operating systems.

The Win32 Internet function set facilitates access to the Internet in the following ways:

•	Eliminates the need to embed knowledge of TCP/IP and Windows Sockets.

By converting the Internet protocols into task-oriented functions, applications do not have to write Windows Sockets code or be familiar with the TCP/IP protocol. One or several Windows Sockets function calls can be executed by each Internet function call.

•	Eliminates the need to embed knowledge of Internet protocols.

While the concepts supported by the Internet protocols such as FTP and HTTP are simple, the actual implementation of these protocols can be complex. For example: FTP servers return ASCII text file directory listings; parsing these listings requires specific knowledge of the format returned by each FTP server. By encapsulating this functionality underneath the Internet functions, directory parsing is solved once for all applications using the FTP protocol. This provides consistent behavior across applications.

•	Provides a constant set of functions in an environment of rapidly changing and evolving protocols.

Keeping pace with the changes in Internet protocols is a challenge when writing applications. By defining a set of functions that remains constant, application writers need not update their application every time the underlying protocol changes—only the wininet.dll needs to be changed. In addition, advanced protocol features, such as firewall-friendly FTP and Gopher+, can also be implemented without changing applications.

•	Follows Win32 function standards.

The Internet extensions for Win32 are similar to the traditional Win32 functions in how they treat such elements as buffer management and error returns. Application programmers familiar with the Win32 function set will find that the Internet extensions for Win32 return information in a format familiar to the Win32 programmer. Furthermore, application programmers will find it easy to use the returned information in other Win32 functions.

•	Provides both ANSI and Unicode versions of functions.

Internet protocols use Latin 1 character sets. However, Latin 1 and ANSI differ in a few character mappings. The ANSI versions of the Internet functions for Win32 do not perform any mappings between ANSI and Latin 1—they return what they receive from the server and pass to the server exactly what they receive from the application. The Internet functions for Win32 provide both ANSI and Unicode entry points to facilitate Unicode-only applications.

•	Provides full access to Internet protocols.

Occasionally, applications will need to access extended features of the Internet protocols. The Win32 Internet functions help to provide such access.

•	Enables high-performance, multithreaded Internet applications.

The Win32 Internet functions are fully "re-entrant" and multithread safe. Multithreaded applications can make simultaneous calls into the functions from different threads without adverse effects. The Internet functions themselves complete any necessary synchronization.

The Win32 Internet functions focus on making Internet client applications easier. The Internet functions are not intended to make it easier to write Internet servers. This is because servers must be able to control how the protocol is accessed and how I/O is performed, in order to achieve the high performance necessary for high-traffic servers.

In addition, the Win32 Internet functions are not intended to solve the general issue of access to mail and news servers.


Overview of the Win32 Internet Functions

The following table summarizes the Win32 Internet functions. This table also shows the dependencies between functions by indenting the dependent functions. A dependent (indented) function can only be called after the head function that precedes it is called. This is because the head function, in most cases, returns a handle and sets up a state at the protocol level, both of which are required to successfully execute the dependent function or functions.

InternetOpen	Initializes the application's use of the Internet Extensions for Win32.
InternetOpenUrl	Begins retrieving an FTP, Gopher, or HTTP URL.
InternetReadFile	Reads URL data.
InternetCloseHandle	Stops reading data from the URL.
InternetSetStatusCallback	Sets a function which is called with status information.
InternetQueryOption	Queries the setting of an Internet option.
InternetSetOption	Sets an Internet option.
FTP
InternetConnect	Opens an FTP session with a server.  Logs on the user.
FtpFindFirstFile	Starts file enumeration in the current directory.
InternetFindNextFile	Continues file enumeration.
InternetCloseHandle	Ends directory file enumeration.
FtpGetFile	Retrieves an entire file from the server.
FtpPutFile	Writes an entire file to the server.
FtpDeleteFile	Deletes a file on the server.
FtpRenameFile	Renames a file on the server.
FtpOpenFile	Initiates access to a file on the server for either reading or writing.
InternetReadFile	Reads data from an open file.
InternetWriteFile	Writes data to an open file.
InternetCloseHandle	Ends reading/writing to/from a file on the server.
FtpCreateDirectory	Creates a new directory on the server.
FtpRemoveDirectory	Deletes a directory on the server.
FtpSetCurrentDirectory	Changes the client's current directory on the server.
FtpGetCurrentDirectory	Returns the client's current directory on the server.
FtpCommand	Issues an arbitrary command to the FTP server.
InternetGetLastResponseInfo	Retrieves the text of the server's response to the FTP command.
InternetCloseHandle	Closes the FTP session.
Gopher
InternetConnect	Indicates a Gopher server the application is interested in accessing
GopherFindFirstFile	Starts enumerating a Gopher directory listing
InternetFindNextFile	Continues Gopher directory enumeration
InternetCloseHandle	Terminates Gopher directory enumeration
GopherOpenFile	Starts retrieval of a Gopher object
InternetReadFile	Reads data from a Gopher object
InternetCloseHandle	Completes the reading of a Gopher object
GopherCreateLocator	Forms a Gopher locator for use in other Gopher function calls
GopherGetAttribute	Retrieves attribute information on the Gopher object
InternetCloseHandle	Indicates that the application is no longer interested in the server
HTTP (World Wide Web)
InternetConnect	Indicates an HTTP server the application is interested in accessing
HttpOpenRequest	Opens an HTTP request handle
HttpAddRequestHeaders	Adds HTTP request headers to the HTTP request handle
HttpSendRequest	Sends the specified request to the HTTP server
InternetReadFile	Reads a block of data from an outstanding HTTP request
HttpQueryInfo	Queries information about an HTTP request
InternetCloseHandle	Closes an open HTTP request handle
InternetCloseHandle	Indicates that the application is no longer interested in the server
InternetCloseHandle	Completes the application's use of the Internet Extensions for Win32


Handles

The handles returned by the Win 32 Internet functions are not native system handles. In other words, Win32 routines, such as ReadFile and CloseHandle, will not work on Internet handles. This is because Internet handles can only be used for the corresponding Internet funcitons for which they are intended.

Any of the handles returned from the Internet functions are closed with the InternetCloseHandle function. If a handle is closed while there is still outstanding activity on the handle, the activity is aborted. Note that failing to close valid handles returned from the Internet functions can result in resource leaks.


Error Handling

The Win32 Internet functions return error information in the same manner as all Win32 functions. Function return values indicate whether a function is successful or not, either by returning a BOOL where TRUE indicates success and FALSE indicates failure, or by returning a handle of type HINTERNET. With HINTERNET, a NULL value indicates failure while any other value indicates a successful call.

If a function fails, the application can call the Win32 Internet GetLastError function to retrieve a specific error code for the failure. In addition, the FTP and Gopher protocols let servers return additional textual error information. For these protocols, applications can use the InternetGetLastResponseInfo function to retrieve error text.

Both GetLastError and InternetGetLastResponseInfo operate on a per-thread basis. In other words, if two threads make Internet function calls at approximately the same time, error information will be returned for each of the individual threads so that there is no conflict between the threads. However, only the thread which successfully made the call will receive the error information for the function.


Multithreaded Access

All the Internet Extensions for Win32 are re-entrant in the sense that there can be multiple calls to an individual function from different threads. All the functions complete any necessary synchronization. However, multiple simultaneous calls using the same Internet connection can lead to unpredictable results.

For example, if an application has used FtpOpenFile to begin downloading a file from an FTP server and two threads simultaneously make calls to InternetReadFile, there is no guarantee as to which thread's call will be completed first, or the order of the data returned to each thread. Applications which use multiple threads for the same Internet connection are responsible for any necessary synchronization between threads to ensure a predictable return of information.


Canceling Requests

All the Win32 Internet functions are synchronous. In some instances, an application can cancel an outstanding request because of user action. A request can be canceled by using the InternetCloseHandle function to close the handle on which the request is outstanding. Canceling a request in this manner will normally abort the connection to the server and require the application to re-establish the connection if it wants to communicate further with the server.


Unicode Support

All the Win32 Internet functions using string arguments on input or output have both ANSI and Unicode versions. As with all Win32 functions, the ANSI functions have "A" as the final character of their name while the Unicode functions have "W." In Windows® 95 and Windows NT™, both the ANSI and Unicode versions of the functions are implemented.

Because the underlying Internet protocols pass all information in Latin 1, the Unicode versions of the Win32 Internet functions must do translations to and from ANSI. In some cases, because it is not possible to convert a Unicode string to ANSI, the Unicode functions can fail. However, this will not be a problem, generally, because in the cases where the translation fails there is no ANSI equivalent, so the requested object could not exist.

The Win32 Internet functions do not translate sent or received content. For example, when calling a Unicode function to retrieve a file from an FTP server, the application must specify the filename in Unicode. However, the file data is returned to the application exactly as the FTP server has stored it.


General Win32 Internet Functions

The General Win32 Internet Functions deal with basic internet file manipulation actions.


InternetOpen

The InternetOpen function initializes an application's use of the Win32 Internet functions.

HINTERNET InternetOpen(

LPCTSTR lpszCallerName,
DWORD dwAccessType,
LPCTSTR lpszProxyName,
INTERNET_PORT nProxyPort,
DWORD dwFlags
);
Parameters

lpszCallerName

A string that identifies the name of the application or entity that is calling the Internet functions (for example, Microsoft Internet Browser). This name is used as the user agent in the HTTP protocol.

dwAccessType

The type of access required. These are the valid parameters:

PRE_CONFIG_INTERNET_ACCESS:	Preconfigured (registry)
LOCAL_INTERNET_ACCESS:	Direct to Internet
GATEWAY_INTERNET_ACCESS:	Through the gateway
CERN_PROXY_ INTERNET_ACCESS:	ThroughCERN proxy
lpszProxyName

The name of the preferred CERN proxy if CERN_PROXY_INTERNET_ACCESS is requested.

nProxyPort

If using CERN_PROXY_INTERNET_ACCESS, this specifies the port that the CERN proxy uses.  If this value is INVALID_PORT_NUMBER, then the default port (80) is used.

dwFlags

Used to indicate various options such as caching and asynchronous behavior.  The possible values include:

INTERNET_OPEN_FLAG_NO_CACHE	Do not cache the data, either locally or in any gateways.
INTERNET_FLAG_ASYNC	Future operations on this handle may fail with ERROR_IO_PENDING. A status callback will be made with INTERNET_STATUS_REQUEST_COMPLETE. This callback will be on a different thread than the original request.  A status callback routine must be registered or the functions will be completed synchronously.
Return Value

The InternetOpen function returns a valid handle that the application passes to subsequent Win32 Internet functions. If InternetOpen fails, it will return a NULL value. The application retrieve a specific error code with the GetLastError function.

Remarks

The InternetOpen function is the first Win32 Internet function called by an application. It tells the Internet DLL to initialize internal data structures and prepare for future calls from the application. When the application is finished using the Internet function, it should call InternetCloseHandle to free the HINTERNET and any other resources. If dwFlags includes INTERNET_FLAG_ASYNC, then all handles derived from this handle will have asynchronous behavior as long as a status callback routine is registered. To cause a function to be completed synchronously, set the dwContext to zero for that call.

See Also

InternetCloseHandle


InternetCloseHandle

The InternetCloseHandle function is used to close any Internet handle opened by an application.

BOOL InternetCloseHandle(

HINTERNET hInet
);
Parameters

hInet

A valid Internet handle to be closed.

Return Value

a value of TRUE is returned, if the handle was closed successfully. If an error occurred, a value of FALSE will be returned. In this case, the application can call GetLastError to retrieve a specific error code.

Remarks

The InternetCloseHandle function is used to close all Internet handles (type HINTERNET) and free any resources associated with the handle. If there are any pending operations on the handle, they are terminated and any outstanding data is discarded. If a thread is blocking in a call to the Internet DLL, another thread in the application can call InternetCloseHandle on the Internet handle being used by the first thread to cancel the operation and unblock the first thread.

When an application has finished using the Internet DLL, it should close the HINTERNET returned from InternetOpen by calling this function.

See Also

FtpFindFirstFile, FtpOpenFile, GopherFindFirstFile, HttpOpenRequest, InternetConnect, InternetOpen


InternetConnect

The InternetConnect function opens an FTP, Gopher, or HTTP session for the specified site.

HINTERNET InternetConnect(

HINTERNET hInternetSession,
LPCTSTR lpszServerName,
INTERNET_PORT nServerPort,
LPCTSTR lpszUsername,
LPCTSTR lpszPassword,
DWORD dwService,
DWORD dwFlags,
DWORD dwContext
);
Parameters

hInternetSession

A handle to the current Internet session returned by InternetOpen.

lpszServerName

Points to a null-terminated string that specifies the host name of an Internet server. Alternately, the string can contain the IP number of the site in ASCII dotted-decimal format (for example, 11.0.1.45).

nServerPort

The TCP/IP port on the server to connect to. If nServerPort is INVALID_PORT_NUMBER (0), then the default port for the specified service is used.

lpszUsername

Points to a null-terminated string that specifies the name of the user to log in. If NULL, an appropriate default is used. For the FTP protocol, the default is anonymous.

lpszPassword

Points to a null-terminated string that specifies the password to use to log in. If both lpszPassword and lpszUsername are NULL, the default anonymous password is used. In the case of FTP, the default anonymous password is the user's email name. If lpszPassword is NULL (or an empty string) but lpszUsername is not NULL, a blank password is used. The following table describes the behavior for the four possible settings of lpszUsername and lpszPassword:

lpszUsername	lpszPassword	Username sent to FTP	Password sent to FTP
		server	server
NULL or ""	NULL or ""	"anonymous"	User's email name
Non-NULL String	NULL or ""	lpszUsername	""
NULL	Non-NULL String	ERROR	ERROR
Non-NULL String	Non-NULL String	lpszUsername	lpszPassword
dwService

The type of service to access. This can be one of INTERNET_SERVICE_FTP, INTERNET_SERVICE_GOPHER, or INTERNET_SERVICE_HTTP.

dwFlags

Specifies the flags specific to the service used. The possible values for these are:

dwService	dwFlags supported
INTERNET_SERVICE_FTP	INTERNET_CONNECT_FLAG_PASSIVE	Use passive mode in all data connections for this FTP session
dwContext

An application-defined value that is used to identify the application context for the returned handle in callbacks.

Return Value

If the connection is successful, a valid handle to the FTP, Gopher, or HTTP session is returned. If the connection attempt fails, NULL is returned. The application can then call GetLastError to retrieve a specific error code. Applications can also use InternetGetLastResponseInfo to determine why access to the service was denied.

Remarks

The InternetConnect function is required before communicating with any Internet service. For some protocols InternetConnect actually establishes a connection with the server, while for others, such as Gopher, the actual connection is not established until the application requests a specific transaction. The reason for having a connect function for all protocols, even those which do not use persistent connections, is that it allows the application to communicate common information about several requests using a single function call. In addition, is also allows for future versions of Internet protocols which do not require the high cost of connection establishment for every request the client performs.

For maximum efficiency, applications using the Gopher and HTTP protocols should try to minimize calls to InternetConnect and not call it for every transaction requested by the user. One way to accomplish this is to keep a small cache of handles returned from InternetConnect so that when the user makes a request to a previously accessed server, the session handle is still available.

Applications interested in displaying any multiline text information sent by an FTP server can use InternetGetLastResponseInfo to retrieve it.

For FTP connections, if lpszUsername is NULL, InternetConnect will send the string anonymous as the username. If lpszPassword is NULL, InternetConnect will attempt to use the user's email name as the password.

To close the handle returned from InternetConnect, the application should call InternetCloseHandle. This function will disconnect the client from the server and free all resources associated with the connection.

See Also

InternetCloseHandle


InternetOpenUrl

The InternetOpenUrl function begins reading an FTP, Gopher, or HTTP Universal Resource Locator (URL).

HINTERNET InternetOpenUrl(

HINTERNET hInternetSession,
LPCTSTR lpszUrl,
LPCTSTR lpszHeaders,
DWORD dwHeadersLength,
DWORD dwFlags,
DWORD dwContext
);
Parameters

hInternetSession

A handle to the current Internet session returned by InternetOpen.

lpszUrl

The name of the URL to begin reading. Only URLs beginning with "ftp:", "gopher:", or "http:" are supported.

lpszHeaders

A pointer to a string containing the headers to be sent to the Http server. (See the lpszAdditional parameter to HttpSendRequest for more details.)

dwHeadersLength

The length, in characters, of the additional headers. If this is -1L and lpszHeaders is non-NULL, then lpszHeaders is assumed to be zero-terminated (ASCIIZ) and the length is calculated.

dwFlags

Flags describing how to handle this session. The valid flags are:

INTERNET_OPEN_FLAG_NO_CACHE	Do not cache the data, either locally or in any gateways.
INTERNET_OPEN_FLAG_RAW_DATA	By default, InternetOpenUrl returns HTML formatted for directories.  This overrides the default to return the raw data (WIN32_FIND_DATA structures for ftp, and GOPHER_FIND_DATA structures for gopher.)
INTERNET_OPEN_FLAG_USE_EXISTING	If possible, reuse the existing connections to the server for new requests generated by InternetOpenUrl instead of creating a new session for each request.
dwContext

An application-defined value that is passed with the returned handle in any callbacks.

Return Value

If the connection is successfully established, a valid handle to the FTP, Gopher, or HTTP URL is returned. If the open attempt fails, NULL is returned. The application can then call GetLastError to retrieve a specific error code. Applications can also use InternetGetLastResponseInfo to determine why access to the service was denied.

Remarks

The InternetOpenUrl function is a general function and is useful for retrieving data over any of the protocols supported by the Internet functions for Win32. It is particularly useful when the calling application does not care about accessing the particulars of a protocol, but simply wants to retrieve the data corresponding to a URL. The InternetOpenUrl function parses the URL string, establishes a connection to the server, and gets ready to download the data identified by the URL. The application should use InternetReadFile to retrieve the URL data.

Applications do not need to call InternetConnect prior to InternetOpenUrl.

Use InternetCloseHandle to close the handle returned from InternetOpenUrl. However, closing the handle before all the URL data has been read will result in the connection being terminated.

See Also

HttpSendRequest, InternetCloseHandle, InternetOpen, InternetReadFile


InternetReadFile

The InternetReadFile function reads data from a handle opened by the InternetOpenUrl, FtpOpenFile, GopherOpenFile, or HttpOpenRequest functions.

BOOL InternetReadFile(

HINTERNET hFile,
LPVOID lpBuffer,
DWORD dwNumberOfBytesToRead,
LPDWORD lpdwNumberOfBytesRead
);
Parameters

hFile

A valid handle returned from a previous call to InternetOpenUrl, FtpOpenFile, GopherOpenFile, or HttpOpenRequest.

lpBuffer

Points to the buffer that receives the data read.

dwNumberOfBytesToRead

Specifies the number of bytes to read.

lpNumberOfBytesRead

Points to the number of bytes read by this call. The InternetReadFile function sets this value to zero before doing any work or error checking.

Return Value

If the function succeeds, the return value is TRUE. If it fails, a value of FALSE is returned. The GetLastError function can be used to retrieve extended error information. The InternetGetLastResponseInfo function can also be used when necessary.

Remarks

If the return value is TRUE and the number of bytes read is zero, then the transfer has been completed and there are no more bytes to be read on the handle. This is analogous to reaching EOF in a local file. The application should then call InternetCloseHandle.

The buffer pointed to by lpBuffer is not always filled by calls to InternetReadFile, as sufficient data may not have arrived from the server to do so. When reading HTML data, for the first read posted the buffer must be large enough to hold the HTML headers. When reading HTML-encoded directory entries, the buffer must be large enough to hold at least one complete entry.

See Also

FtpOpenFile, GopherOpenFile, HttpOpenRequest, InternetCloseHandle, InternetOpenUrl


InternetWriteFile

The InternetWriteFile function writes data to an open Internet file.

BOOL InternetWriteFile(

HINTERNET hFile,
LPVOID lpBuffer,
DWORD dwNumberOfBytesToWrite,
LPDWORD lpdwNumberOfBytesWritten
);
Parameters

hFile

A valid handle returned from a previous call to FtpOpenFile.

lpBuffer

Points to the buffer containing the data to be written to the file.

dwNumberOfBytesToWrite

Specifies the number of bytes to write to the file.

lpNumberOfBytesWritten

Points to the number of bytes written by this call. The InternetWriteFile function sets this value to zero before doing any work or error checking.

Return Value

If the function succeeds, the return value is TRUE. If the function fails, a value of FALSE is returned. The GetLastError function can be used to retrieve extended error information. The InternetGetLastResponseInfo function can also be used when necessary.

Remarks

When the application is sending sending data, it must call the InternetCloseHandle function to end the data transfer.

See Also

FtpOpenFile, InternetCloseHandle


InternetFindNextFile

The InternetFindNextFile function continues a file search from a previous call to FtpFindFirstFile or GopherFindFirstFile.

BOOL InternetFindNextFile(

HINTERNET hFind,
LPVOID lpvFindData
);
Parameters

hFind

A valid handle returned from either FtpFindFirstFile or GopherFindFirstFile.

lpvFindData

Points to a buffer that receives information about the found file or directory. The format of the information placed in the buffer depends on the protocol in use. The FTP protocol returns a WIN32_FIND_DATA structure and the Gopher protocol returns a GOPHER_FIND_DATA structure.

Return Value

If the function succeeds, the return value is TRUE. If it fails, a value of FALSE is returned. The GetLastError function can be used to retrieve extended error information. If no matching files can be found, the GetLastError function returns ERROR_NO_MORE_FILES.

See Also

FtpFindFirstFile, GopherFindFirstFile


InternetQueryOption

The InternetQueryOption function queries an Internet option on the specified handle.

BOOL InternetQueryOption(

HINTERNET hInternet,
DWORD dwOption,
LPVOID lpBuffer,
LPDWORD lpdwBufferLength
);
Parameters

hInternet

The Internet handle on which to query information.

dwOption

The Internet option to query. The following options are defined:

Value	Meaning
INTERNET_OPTION_CALLBACK	Returns the address of the callback function defined for this handle.
INTERNET_OPTION_CONNECT_TIMEOUT	A time-out value in milliseconds to use for Internet  connection requests. If a connection request takes longer than this time-out, then the request is canceled. The default time-out is infinite.
INTERNET_OPTION_CONNECT_RETRIES	A retry count to use for Internet connection requests. If a connection attempt still fails after the specified number of tries, then the request is canceled. The default is five retries.
INTERNET_OPTION_CONNECT_BACKOFF	A delay value in milliseconds to wait between connection retries.
INTERNET_OPTION_CONTROL_SEND_TIMEOUT	A time-out value in milliseconds to use for nondata (control) Internet send requests. If a nondata send request takes longer than this time-out, then the request is canceled. The default time-out is infinite. Currently, this value only has meaning for FTP sessions.
INTERNET_OPTION_CONTROL_RECEIVE_TIMEOUT	A time-out value in milliseconds to use for nondata (control) Internet receive requests. If a nondata receive request takes longer than this time-out, then the request is canceled. The default time-out is infinite. Currently, this value only has meaning for FTP sessions.
INTERNET_OPTION_DATA_SEND_TIMEOUT	A time-out value in milliseconds to use for data Internet send requests. If a data send request takes longer than this time-out, then the request is canceled. The default time-out is infinite.
INTERNET_OPTION_DATA_RECEIVE_TIMEOUT	A time-out value in milliseconds to use for data Internet receive requests. If a data receive request takes longer than this time-out, then the request is canceled. The default time-out is infinite.
INTERNET_OPTION_HANDLE_TYPE	Returns the type of the Internet handle passed in. Possible return values include: INTERNET_HANDLE_TYPE_INTERNET INTERNET_HANDLE_TYPE_CONNECT_FTP INTERNET_HANDLE_TYPE_CONNECT_GOPHER INTERNET_HANDLE_TYPE_CONNECT_HTTP INTERNET_HANDLE_TYPE_FTP_FIND INTERNET_HANDLE_TYPE_FTP_FIND_HTML INTERNET_HANDLE_TYPE_FTP_FILE INTERNET_HANDLE_TYPE_FTP_FILE_HTML INTERNET_HANDLE_TYPE_GOPHER_FIND INTERNET_HANDLE_TYPE_GOPHER_FIND_HTML INTERNET_HANDLE_TYPE_GOPHER_FILE INTERNET_HANDLE_TYPE_GOPHER_FILE_HTML INTERNET_HANDLE_TYPE_HTTP_REQUEST
INTERNET_OPTION_CONTEXT_VALUE	Returns the context value associated with this Internet handle.
lpBuffer

A buffer which receives the option setting.

lpdwBufferLength

A pointer to a DWORD containing the length of lpBuffer. On return this contains the length of the data placed into lpBuffer.

Return Value

A value of TRUE is returned, if the operation was successful. If an error occurred, a value of FALSE is returned. In this case,  the application can call GetLastError to retrieve a specific error code.


InternetSetOption

The InternetSetOption function sets an Internet option on the specified handle.

BOOL InternetSetOption(

HINTERNET hInternetSession,
DWORD dwOption,
LPVOID lpBuffer,
DWORD dwBufferLength
);
Parameters

hInternetSession

The Internet handle on which to set information.

dwOption

The Internet option to set. See InternetQueryOption for a list of possible options.

lpBuffer

A buffer which contains the option setting.

dwBufferLength

The length of lpBuffer.

Return Value

A value of TRUE is returned, if the operation was successful. If an error occurred, a value of FALSE is returned. The application can call GetLastError to retrieve a specific error code.


InternetGetLastResponseInfo

The InternetGetLastResponseInfo function retrieves error text from the last Win32 Internet function which failed.

BOOL InternetGetLastResponseInfo(

LPDWORD lpdwError,
LPTSTR lpszBuffer,
LPDWORD lpdwBufferLength
);
Parameters

lpdwError

Receives an error code pertaining to the operation that failed.

lpszBuffer

A buffer which receives the error text.

lpdwBufferLength

On input, this is the size of the buffer pointed to by lpszBuffer. On output, this is the size of the string written to the buffer.

Return Value

A value of TRUE is returned,  if error text was successfully written to the buffer. If an error occurred, a value of FALSE is returned. In this case, the application can call GetLastError to retrieve a specific error code. If the buffer is too small to hold all the error text, GetLastError returns ERROR_BUFFER_OVERFLOW. The lpdwBufferLength parameter will contain the minimum buffer size required to return all the error text.

Remarks

The FTP and Gopher protocols return textual information along with most errors. Applications can retrieve this extended error information by using the InternetGetLastResponseInfo function whenever a GetLastError (after an unsuccessful function call) returns ERROR_INTERNET_EXTENDED_ERROR.

The buffer pointed to by lpszBuffer must be large enough to hold both the error string and a zero terminator at the end of the string. However, the value returned in lpdwBufferLength does not include the terminating zero.


InternetSetStatusCallback

The InternetSetStatusCallback function sets up a callback function that the Win32 Internet functions call when progress is made during an operation.

INTERNET_STATUS_CALLBACK InternetSetStatusCallback(

INTERNET_STATUS_CALLBACK lpfnInternetCallback
);
Parameters

lpfnInternetCallback

A pointer to a callback function to call whenever progress is made, or NULL to remove the existing callback function.

Return Value

This function returns the previously defined status callback function, returns NULL if the there was no previously defined status callback, or returns INVALID_INTERNET_STATUS_CALLBACK if the callback is not valid.

Remarks

Many of the Win32 Internet functions perform several operations on the network. Each of these operations can take time to be completed, and each has the possibility for failure. In some instances, it is convenient for an application to display processing status during a long-term operation. Setting up an Internet status callback function enables this. The status callback cannot be removed as long as any callbacks or any asynchronous functions are pending.

After calling InternetSetStatusCallback, the callback is called from within any Win32 Internet function performing network operations that may take time. The function is defined as:

BOOL lpfnInternetCallback (

DWORD dwContext,
DWORD dwInternetStatus,
LPVOID lpvStatusInformation,
DWORD dwStatusInformationLength
);
The dwInternetStatus parameter indicates the operation the Internet DLL is performing. The contents of lpvStatusInformation depends on the value of dwInternetStatus, and dwStatusInformationLength indicates the length of the data included in lpvStatusInformation. The following status values for dwInternetStatus are defined as:

Value	Meaning
INTERNET_STATUS_RESOLVING_NAME	Looking up the IP address of the name contained in lpvStatusInformation.
INTERNET_STATUS_NAME_RESOLVED	Successfully found the IP address of the name contained in lpvStatusInformation.
INTERNET_STATUS_CONNECTING_TO_SERVER	Connecting to the socket address (SOCKADDR) pointed to by lpvStatusInformation.
INTERNET_STATUS_CONNECTED_TO_SERVER	Successfully connected to the socket address (SOCKADDR) pointed to by lpvStatusInformation.
INTERNET_STATUS_SENDING_REQUEST	Sending the information request to the server. lpvStatusInformation is NULL.
INTERNET_STATUS_ REQUEST_SENT	Successfully sent the information request to the server. The lpvStatusInformation parameter is NULL.
INTERNET_STATUS_RECEIVING_RESPONSE	Waiting for the server to respond to a request. The lpvStatusInformation parameter is NULL.
INTERNET_STATUS_RESPONSE_RECEIVED	Successfully received a response from the server.The lpvStatusInformation parameter is NULL.
INTERNET_STATUS_CLOSING_CONNECTION	Closing the connection to the server. The  lpvStatusInformation parameter is NULL.
INTERNET_STATUS_CONNECTION_CLOSED	Successfully closed the connection to the server. The lpvStatusInformation parameter is NULL
INTERNET_STATUS_HANDLE_CREATED	Used by InternetConnect to indicate it has created the new handle. This allows the application to call InternetCloseHandle from another thread, if the connect is taking too long.
INTERNET_STATUS_REQUEST_COMPLETE	An asynchronous operation has been completed. See InternetOpen for details on INTERNET_FLAG_ASYNC. The lpvStatusInformation parameter will be NULL and dwStatusInformationLength will contain the final completion status of the asynchronous function.  If this is ERROR_INTERNET_EXTENDED_ERROR, then  the application can retrieve the server error information by using InternetGetLastResponseInfo.
A return value of FALSE from the lpfnInternetCallback cancels the operation and causes the Win32 Internet function to fail.

See Also

InternetCloseHandle, InternetConnect, InternetGetLastResponseInfo, InternetOpen


FTP Functions

The FTP Functions deal with the FTP file and directory manipulation and navigation.


FtpFindFirstFile

The FtpFindFirstFile function begins searching the current directory of the given FTP session. File and directory entries are returned to the application in the WIN32_FIND_DATA structure.

HINTERNET FtpFindFirstFile(

HINTERNET hFtpSession,
LPCTSTR lpszSearchFile,
LPWIN32_FIND_DATA lpFindFileData,
DWORD dwContext
);
Parameters

hFtpSession

A valid handle to an FTP session returned from InternetConnect.

lpszSearchFile

Points to a null-terminated string that specifies a valid directory pathname or filename for the FTP server's file system.

lpFindFileData

Points to the WIN32_FIND_DATA structure that receives information about the found file or directory.

dwContext

An application-defined value that associates this search with any application data. This is only used if the application has already set up a status callback with InternetSetStatusCallback.

Return Value

A valid handle for the request is returned, if the directory enumeration was started successfully. If an error occurred, NULL is returned. In this case, an application macany call GetLastError to retrieve a specific error code. If no matching files can be found, the GetLastError function returns ERROR_NO_MORE_FILES.

Remarks

This function will enumerate both files and directories.

The FtpFindFirstFile function is similar to the Win32 function FindFirstFile. Note, however, an important difference is that only one FtpFindFirstFile can occur at a time within a given FTP session, and the enumerations, therefore, are correlated with the FTP session handle instead. This is because the FTP protocol allows only a single, directory enumeration on a session.

After calling FtpFindFirstFile, and until calling InternetCloseHandle, the application cannot call FtpFindFirstFile again on a given FTP session handle. In that case, calls to the FtpFindFirstFile function will fail with error code ERROR_FTP_TRANSFER_IN_PROGRESS.

After beginning a directory enumeration with FtpFindFirstFile, the InternetFindNextFile function can be used to continue the enumeration.

The InternetCloseHandle function is used to close the handle returned from FtpFindFirstFile. If the InternetCloseHandle function closes the handle before InternetFindNextFile fails with ERROR_NO_MORE_FILES, this will result in the directory enumeration being terminated.

Because the FTP protocol provides no standard means of enumerating, some of the common information pertaining to files (such as file creation date and file) is not always available or correct. In this case, FtpFindFirstFile and InternetFindNextFile fill in unavailable information with a "best guess" based on available information. For example, creation and last access dates will often be the same as the file's modification date.

The application cannot call FtpFindFirstFile between calls to FtpOpenFile and InternetCloseHandle.

See Also

FtpOpenFile, InternetCloseHandle, InternetFindNextFile, InternetSetStatusCallback


FtpGetFile

The FtpGetFile function retrieves a file from the FTP server and stores it under the specified filename, creating a new local file in the process.

BOOL FtpGetFile(

HINTERNET hFtpSession,
LPCTSTR lpszRemoteFile,
LPCTSTR lpszNewFile,
BOOL fFailIfExists,
DWORD dwFlagsAndAttributes,
DWORD dwFlags,
DWORD dwContext
);
Parameters

hFtpSession

A valid handle to an FTP session.

lpszRemoteFile

A pointer to a null-terminated string that contains the name of the file to retrieve from the remote system.

lpszNewFile

A pointer to a null-terminated string that contains the name of the file to create on the local system.

fFailIfExists

A Boolean flag that indicates whether the function should proceed if a local file of the specified name already exists. If fFailIfExists is TRUE and the local file exists, FtpGetFile fails.

dwFlagsAndAttributes

Specifies the file attributes and flags for the new file. This can be any combination of FILE_ATTRIBUTE_* and INTERNET_OPEN_FLAG_* file attributes. See CreateFile for further information on FILE_ATTRIBUTE_* attributes, and InternetOpenUrl for further information on INTERNET_OPEN_FLAG_* flags.

dwFlags

Specifies the conditions under which the transfer occurs. May be any of the FTP_TRANSFER_TYPE_* constants. For further information on the FTP_TRANSFER_TYPE_* constants, see FtpOpenFile.

dwContext

An application-defined value to associate this search with any application data. This is only used if the application has already set up a status callback with InternetSetStatusCallback.

Return Value

A value of TRUE is returned, if the file was retrieved successfully. If an error occurred, a value of FALSE is returned. In this case, an application can call GetLastError to get a specific error code.

Remarks

The FtpGetFile function is a high-level routine that handles all the bookkeeping and overhead associated with reading a file from an FTP server and storing it locally. Applications that want to retrieve file data only or that want to have close control over the file transfer, should use the FtpOpenFile and InternetReadFile functions.

If the dwTransferType specifies FILE_TRANSFER_TYPE_ASCII, translation of the file data will convert control and formatting characters to local equivalents. The default transfer is binary mode where the file is downloaded in the same format as it is stored on the server.

Both lpszRemoteFile and lpszNewFile can be either partially qualified filenames relative to the current directory or fully qualified. A backslash ("\") or forward slash ("/") can be used as the directory separator for either name. The FtpGetFile function translates the directory name separators to the appropriate character before using it.


FtpPutFile

The FtpPutFile function stores a file on the FTP server.

BOOL FtpPutFile(

HINTERNET hFtpSession,
LPCTSTR lpszLocalFile,
LPCTSTR lpszNewRemoteFile,
DWORD dwFlags
DWORD dwContext
);
Parameters

hFtpSession

A valid handle to an FTP session.

lpszLocalFile

A pointer to a null-terminated string that contains the name of the file to send from the local system.

lpszNewRemoteFile

A pointer to a null-terminated string that contains the name of the file to create on the remote system.

dwFlags

Specifies the conditions under which the transfer occurs. This can be any combination of FTP_TRANSFER_* defined constants. For further information on the FTP_TRANSFER_* constants, see FtpOpenFile.

dwContext

An application-defined value to associate this search with any application data. This is used only if the application has already set up a status callback with InternetSetStatusCallback.

Return Value

A value of TRUE is returned,  if the file was stored successfully. If an error occurred, a value of FALSE is returned. In this case, an application can call GetLastError to get a specific error code.

Remarks

The FtpPutFile function is a high-level routine that handles all the bookkeeping and overhead associated with reading a file from an FTP server and storing it locally. Applications that want to send file data only or that want to have close control over the file transfer, should use the FtpOpenFile and InternetWriteFile functions.

If the dwTransferType specifies FILE_TRANSFER_TYPE_ASCII, translation of the file data will convert control and formatting characters to local equivalents.

Both lpszNewRemoteFile and lpszLocalFile can be either partially qualified filenames relative to the current directory or fully qualified. A backslash ("\") or forward slash ("/") can be used as the directory separator for either name. The FtpPutFile function translates the directory name separators to the appropriate character before using it.


FtpDeleteFile

The FtpDeleteFile function deletes a file stored on the FTP server.

BOOL FtpDeleteFile(

HINTERNET hFtpSession,
LPCTSTR lpszFileName
);
Parameters

hFtpSession

A valid handle to an FTP session.

lpszFileName

A pointer to a null-terminated string that contains the name of the file to delete on the remote system.

Return Value

A value of TRUE is returned, if the file was deleted successfully. If an error occurred, a value of FALSE is returned. In this case, an application can call GetLastError to get a specific error code.

Remarks

The lpszFile parameter can be either partially qualified filenames relative to the current directory or fully qualified. A backslash ("\") or forward slash ("/") can be used as the directory separator for either name. The FtpDeleteFile funciton translates the directory name separators to the appropriate character before using it.


FtpRenameFile

The FtpRenameFile function renames a file stored on the FTP server.

BOOL FtpRenameFile(

HINTERNET hFtpSession,
LPCTSTR lpszExisting,
LPCTSTR lpszNew
);
Parameters

hFtpSession

A valid handle to an FTP session.

lpszExisting

A pointer to a null-terminated string that contains the name of the file which will have its name on the remote FTP server changed.

lpszNew

A pointer to a null-terminated string that contains the new name for the remote file.

Return Value

A value of TRUE is returned, if the file was renamed successfully. If an error occurred, a value of FALSE is returned. In this case, an application can call GetLastError to get a specific error code.

Remarks

The lpszExisting and lpszNew parameters can be either partially qualified filenames relative to the current directory or fully qualified. A backslash ("\") or forward slash ("/") can be used as the directory separator for either name. The FtpRenameFile function translates the directory name separators to the appropriate character before using it.


FtpOpenFile

The FtpOpenFile function initiates access to a remote file for either writing or reading.

HINTERNET FtpOpenFile(

HINTERNET hFtpSession,
LPCTSTR lpszFileName,
DWORD fdwAccess,
DWORD dwFlags
DWORD dwContext
);
Parameters

hFtpSession

A valid handle to an FTP session.

lpszFileName

A pointer to a null-terminated string that contains the name of the file to access on the remote system.

fdwAccess

Determines how the file will be accessed. This can be either GENERIC_READ or GENERIC_WRITE, but not both.

dwFlags

Specifies the conditions under which subsequent transfers occur.  This can be any of the following FTP_TRANSFER_* constants:

Value	Meaning
FTP_TRANSFER_TYPE_ASCII	The file will be transferred using FTP's ASCII (Type A) transfer method. Control and formatting information will be converted to local equivalents.
FTP_TRANSFER_TYPE_BINARY	The file will be transferred using FTP's Image (Type I) transfer method. The file is transferred exactly as it exists with no changes. This is the default transfer method.
dwContext

An application-defined value to associate this search with any application data. This is only used if the application has already set up a status callback with InternetSetStatusCallback.

Return Value

A valid handle for the request is returned if the file was opened successfully. If an error occurred, NULL is returned. In this case, an application can call GetLastError to get a specific error code.

Remarks

The FtpOpenFile function should be used in these cases:

•	An application has data which it wants to send to an FTP server to be created as a file on the FTP server. The application does not have a local file containing the data. After InternetOpen opens the file with FtpOpenFile, the application will use InternetWriteFile to send the FTP file data to the server.

•	An application wants to retrieve a file from the server into application-controlled memory, instead of writing the file to disk. The application uses InternetReadFile after using InternetOpen to open the file.

•	An application wants a fine level of control over a file transfer. For example, the application may want to display a "thermometer" when downloading a file to give the user an indication that the file transfer is or is not proceeding correctly.

After calling the FtpOpenFile function, and until calling InternetCloseHandle, the application can only call InternetReadFile or InternetWriteFile, InternetCloseHandle, or the FtpFindFirstFile function. Calls to other FTP functions on the same FTP session will fail and set the error code to FTP_ETRANSFER_IN_PROGRESS.

Only one file can be open in a single FTP session. Therefore, no file handle is returned and the application simply uses the FTP session handle when necessary.

The lpszFile parameter can be either partially qualified filenames relative to the current directory or fully qualified. A backslash ("\") or forward slash ("/") can be used as the directory separator for either name. The FtpOpenFile function translates the directory name separators to the appropriate character before using it.

The InternetCloseHandle function is used to close the handle returned from FtpOpenFile. If the InternetCloseHandle function closes the handle before all the data has been transferred, this will result in the transfer being terminated.


FtpCreateDirectory

The FtpCreateDirectory function creates a new directory on the FTP server.

BOOL FtpCreateDirectory(

HINTERNET hFtpSession,
LPCTSTR lpszDirectory
);
Parameters

hFtpSession

A valid handle to an FTP session.

lpszDirectory

A pointer to a null-terminated string that contains the name of the directory to create on the remote system. This can be either a fully qualified pathname or a name relative to the current directory.

Return Value

If the function succeeds, FtpCreateDirectory returns TRUE. If an error occurred the function failed.An application can use GetLastError to retrieve a specific error code. If the error code indicates that the FTP server denied the request to create a directory, InternetGetLastResponseInfo can be used to determine why.

Remarks

Applications should use FtpGetCurrentDirectory to determine the remote site's current working directory, instead of assuming that the remote system uses a hierarchical naming scheme for directories.

The lpszDirectory parameter can be either partially qualified filenames relative to the current directory or fully qualified. A backslash ("\") or forward slash ("/") can be used as the directory separator for either name. The FtpCreateDirectory functions translates the directory name separators to the appropriate character before using it.


FtpRemoveDirectory

The FtpRemoveDirectory function removes the specified directory on the FTP server.

BOOL FtpRemoveDirectory(

HINTERNET hFtpSession,
LPCTSTR lpszDirectory
);
Parameters

hFtpSession

A valid handle to an FTP session.

lpszDirectory

A pointer to a null-terminated string that contains the name of the directory to remove on the remote system. This mcanay be either a fully qualified pathname or a name relative to the current directory.

Return Value

If the function succeeds, the return value is TRUE. Otherwise, an error occurred and the application can use GetLastError to retrieve a specific error code. If the error code indicates that the FTP server denied the request to remove a directory, InternetGetLastResponseInfo can be used to determine why.

Remarks

Applications should use FtpGetCurrentDirectory to determine the remote site's current working directory, instead of assuming that the remote system uses a hierarchical naming scheme for directories.

The lpszDirectory parameter can be either partially qualified filenames relative to the current directory or fully qualified. A backslash ("\") or forward slash ("/") can be used as the directory separator for either name. The FtpRemoveDirectory function translates the directory name separators to the appropriate character before using it.


FtpSetCurrentDirectory

The FtpSetCurrentDirectory function changes to a different working directory on the FTP server.

BOOL FtpSetCurrentDirectory(

HINTERNET hFtpSession,
LPCTSTR lpszDirectory
);
Parameters

hFtpSession

A valid handle to an FTP session.

lpszDirectory

A pointer to a null-terminated string that contains the name of the directory to change to on the remote system. This can be either a fully qualified pathname or a name relative to the current directory.

Return Value

If the function succeeds, the return value is TRUE. Otherwise, an error occurred and the application can use GetLastError to retrieve a specific error code. If the error code indicates that the FTP server denied the request to change to a directory, InternetGetLastResponseInfo can be used to determine why.

Remarks

Applications should use FtpGetCurrentDirectory to determine the remote site's current working directory, instead of assuming that the remote system uses a hierarchical naming scheme for directories.

The lpszDirectory parameter can be either partially qualified filenames relative to the current directory or fully qualified. A backslash ("\") or forward slash ("/") can be used as the directory separator for either name. The FtpSetCurrentDirectory function translates the directory name separators to the appropriate character before using it.


FtpGetCurrentDirectory

The FtpGetCurrentDirectory function retrieves the current directory for the specified FTP session.

BOOL FtpGetCurrentDirectory(

HINTERNET hFtpSession,
LPCTSTR lpszCurrentDirectory,
LPDWORD lpdwCurrentDirectory
);
Parameters

hFtpSession

A valid handle to an FTP session.

lpszCurrentDirectory

Points to the buffer for the current directory string. This null-terminated string specifies the absolute path to the current directory.

lpdwCurrentDirectory

Points to a DWORD containing the length, in characters, of the buffer for the current directory string. The buffer length must include room for a terminating null character. Using a length of MAX_PATH will be sufficient for all pathnames. On return, the DWORD contains the number of characters transferred.

Return Value

If the function succeeds, the return value is TRUE. Otherwise, an error occurred and the application can use GetLastError to retrieve a specific error code. If the error code indicates that the FTP server denied the request to change to a directory, InternetGetLastResponseInfo can be used to determine why.

Remarks

If the lpszCurrentDirectory buffer is not large enough, then on return lpdwCurrentDirectory contains the number of bytes required to retrieve the full, current directory name.


FtpCommand

The FtpCommand function issues an arbitrary command on the FTP server referred to by the session handle.

BOOL FtpCommand(

HINTERNET hFtpSession,
BOOL fExpectResponse,
DWORD dwFlags,
LPCTSTR lpszCommand
DWORD dwContext,
);
Parameters

hFtpSession

A valid handle to an FTP session.

fExpectResponse

A Boolean value indicating whether the command is expected to cause the FTP server to open a data connection on which to send a reply. If TRUE, FtpCommand creates a connection endpoint and negotiates for a connection with the FTP server. The application must use InternetReadFile and InternetCloseHandle to read from and close this data connection.

dwFlags

One of the FTP_TRANSFER_TYPE_* constants. If fExpectResponse is TRUE, this value governs the type of connection constructed with the FTP server.

lpszCommand

A pointer to a null-terminated format string containing the command to send to the FTP server.

dwContext

An application-defined value to associate this search with any application data. This is only used if the application has already set up a status callback with InternetSetStatusCallback.

Return Value

If the function succeeds, the return value is TRUE. Otherwise, an error occurred and the application can use GetLastError to retrieve a specific error code. If the error code indicates that the FTP server denied the request to change to a directory, InternetGetLastResponseInfo can be used to determine why.

Remarks

The application must use InternetGetLastResponseInfo to determine the FTP server's response to the command.

The FtpCommand function ensures that the text sent contains only ASCII-printable characters and filters the string appropriately, adding the necessary end-of-line characters.

If fExpectResponse is TRUE, FtpCommand will issue the appropriate "PORT" or "PASV" command from the FTP protocol.


Gopher Functions

Gopher functions control the creation and use of the Internet Gopher utilities.


GopherCreateLocator

The GopherCreateLocator function creates a Gopher or Gopher+ locator string from its component parts.

BOOL GopherCreateLocator(

LPCTSTR lpszHost,
INTERNET_PORT nServerPort,
LPCTSTR lpszDisplayString,
LPCTSTR lpszSelectorString,
DWORD dwGopherType,
LPCTSTR lpszLocator,
LPDWORD lpdwBufferLength
);
Parameters

lpszHost

A string identifying the name of the host, or a dotted-decimal IP address such as 198.105.232.1.

nServerPort

A port on which the Gopher server at Host lives, in host byte order. If nPort is INVALID_PORT_NUMBER, then the default Gopher port is read from the \etc\services file.

lpszDisplayString

The Gopher document or directory to be displayed.The  lpszDisplayString parameter can be NULL. In this case, the default directory for the Gopher server will be returned.

lpszSelectorString

The selector string to be sent to the Gopher server in order to retrieve information. This can be NULL.

dwGopherType

Specifies whether lpszSelector refers to a directory or document, and whether the request is Gopher+ or Gopher. See GOPHER_FIND_DATA Attributes.

lpszLocator

A pointer to the buffer where the locator string will be returned. If lpszLocator is NULL, lpdwBufferLength receives the needed buffer length but no other processing occurs.

lpdwBufferLength

On input, the length of lpszLocator. On output, the number of bytes written to lpszLocator, or, if the lpszLocator buffer is too small, the number of bytes required to form the locator successfully.

Return Value

A value of TRUE is returned it the function was successful. If it was not, a value of FALSE is returned. In this case, more information can be obained using GetLastError and InternetGetLastResponseInfo.

Remarks

In order to retrieve information from a Gopher server, an application must first get a Gopher "locator" from the Gopher server. The locator, which the application should treat as an opaque token, is normally used for calls to the GopherFindFirstFile function to retrieve a specific piece of information.


GopherGetLocatorType

The GopherGetLocatorType function parses a Gopher locator and determines its attributes.

BOOL GopherGetLocatorType(

LPCTSTR lpszLocator,
LPDWORD lpdwGopherType
);
Parameters

lpszLocator

A Gopher locator string to parse.

lpdwGopherType

Receives the type of the locator. This is a bitmask of any of the following:

Value	Meaning
GOPHER_TYPE_TEXT_FILE	The item is an ASCII text file.
GOPHER_TYPE_DIRECTORY	The item is a directory of additional Gopher items.
GOPHER_TYPE_CSO	The item is a CSO phone book server.
GOPHER_TYPE_ERROR	This indicates an error condition.
GOPHER_TYPE_MAC_BINHEX	The item is a Macintosh file in BINHEX format.
GOPHER_TYPE_DOS_ARCHIVE	The file is a DOS archive file.
GOPHER_TYPE_UNIX_UUENCODED	The item is a UUENCODED file.
GOPHER_TYPE_INDEX_SERVER	The item refers to an index server.
GOPHER_TYPE_TELNET	The item refers to a Telnet server.
GOPHER_TYPE_BINARY	The item is a binary file.
GOPHER_TYPE_REDUNDANT	The item refers to a duplicated server.  The information contained within is a duplicate of the primary server.  The primary server is defined as the last directory entry that did not have a GOPHER_TYPE_REDUNDANT type.
GOPHER_TYPE_TN3270	The item is a TN3270 server.
GOPHER_TYPE_GIF	The item is a GIF graphics file.
GOPHER_TYPE_IMAGE	The item is an image file.
GOPHER_TYPE_BITMAP	The item is a bitmap file.
GOPHER_TYPE_MOVIE	The item is a movie file.
GOPHER_TYPE_SOUND	The item is a sound file.
GOPHER_TYPE_HTML	The item is an HTML document.
GOPHER_TYPE_PDF	The item is a PDF file.
GOPHER_TYPE_CALENDAR	The item is a calendar file.
GOPHER_TYPE_INLINE	The item is an inline file
GOPHER_TYPE_UNKNOWN	The item type is unknown.
GOPHER_TYPE_ASK	The item is an Ask+ item.
GOPHER_TYPE_GOPHER_PLUS	The item is a Gopher+ item.
Remarks

The GopherGetLocatorType function returns information about the item referenced by a Gopher locator. Note that it is possible for multiple attributes to be set on a file.  For example, both GOPHER_TYPE_TEXT_FILE and GOPHER_TYPE_GOPHER_PLUS are set for a text file stored on a Gopher+ server.


GopherFindFirstFile

The GopherFindFirstFile function, given a Gopher locator and some search criteria, creates a session with the server and locates the requested documents, binary files, index servers, or directory trees.

HINTERNET GopherFindFirstFile(

HINTERNET hGopherSession,
LPCTSTR lpszLocator,
LPCTSTR lpszSearchString,
LPGOPHER_FIND_DATA lpFindData
DWORD dwContext
);
Parameters

hGopherSession

A handle to a Gopher session returned by InternetConnect.

lpszLocator

A name of the item to locate. This parameter can be any of the following:

•	A Gopher locator returned in the lpGopherFindData, or a locator field from a previous call to this function or the InternetFindNextFile function.

•	A NULL pointer or zero-length string indicating that the top-most information from a Gopher server is being returned.

•	A locator created by the GopherCreateLocator function.

lpszSearchString

If this request is to an index server, lpszSearchString specifies the strings to search. If the request is not to an index server, lpszSearchString should be NULL.

lpFindData

A pointer to application-supplied buffer which will be filled with a GOPHER_FIND_DATA structure.

dwContext

An application-defined value to associate this search with any application data.

Return Value

If this function is successful, a valid search handle is returned. If it is not, a NULL value is returned. The GetLastError and InternetGetLastResponseInfo functions can be used to obtain more information.

Remarks

The GopherFindFirstFile function closely resembles the Win32 function FindFirstFile. It creates a connection with a Gopher server and then returns a single structure containing information about the first Gopher object referenced by the locator string.

After calling GopherFindFirstFile to retrieve the first Gopher object in an enumeration, the InternetFindNextFile function can be used to retrieve subsequent Gopher objects.

The InternetCloseHandle function is used to close the handle returned from GopherFindFirstFile. If there are any pending operations described by the handle when the application calls InternetCloseHandle, they are canceled or marked close pending. Any open sessions will be terminated and any data waiting to be indicated to the caller will be discarded. Any allocated buffers will be freed.

See Also

InternetFindNextFile


GopherOpenFile

The GopherOpenFile function begins reading a Gopher data file from a Gopher server.

HINTERNET GopherOpenFirst(

HINTERNET hGopherSession,
LPCTSTR lpszLocator,
LPCTSTR lpszView,
DWORD dwFlags,
DWORD dwContext
);
Parameters

hGopherSession

A handle to a Gopher session returned by InternetConnect.

lpszLocator

A string identifying the file to open. Generally, this locator will have been returned from a call to GopherFindFirstFile or InternetFindNextFile. Because the Gopher protocol has no concept of a current directory, the locator is always fully qualified.

lpszView

If several views of the file exist at the server, this parameter describes which file view to open. If lpszView is NULL, the default file view is used.

dwFlags

Any combination of the INTERNET_OPEN_FLAG_* flags. See InternetOpenUrl for further information on INTERNET_OPEN_FLAG_* flags.

dwContext

An application-defined value to associate this operation with any application data.

Return Value

If the file cannot be opened, a NULL value is returned. The GetLastError or InternetGetLastResponseInfo functions can be used to determine the cause of the error.

Remarks

The GopherOpenFile function opens a file at a Gopher server. Because a file cannot be actually opened or locked at a server, this call simply associates location information with a handle that can be used for file-based operations such as InternetReadFile or GopherGetAttribute.

The InternetCloseHandle function is used to close the handle returned from GopherOpenFile. If there are any pending operations described by the handle when the application calls InternetCloseHandle, they are canceled or marked close pending. Any open sessions will be terminated, and any data waiting to be indicated to the caller will be discarded. Any allocated buffers will be freed.

See Also

GopherGetAttribute, InternetReadFile


GopherGetAttribute

The GopherGetAttribute function allows an application to retrieve specific attribute information from the server.

BOOL GopherGetAttribute(

HINTERNET hGopherSession,
LPCTSTR lpszLocator,
LPCTSTR lpszAttributeName,
LPBYTE lpBuffer,
DWORD dwBufferLength,
LPDWORD lpdwCharactersReturned,
GOPHER_ATTRIBUTE_ENUMERATOR lpfnEnumerator,
DWORD dwContext
);
Parameters

hGopherSession

A handle to an Gopher session returned by InternetConnect.

lpszLocator

A string identifying the item at Gopher server on which to return attribute information.

lpszAttributeName

A pointer to space-delimited string specifying the names of attributes to return.

lpBuffer

A pointer to a user-supplied buffer from which attribute information is retrieved.

dwBufferLength

The size of lpBuffer in bytes.

lpdwCharactersReturned

The number of characters read into lpBuffer.

lpfnEnumerator

Points to a callback enumeration function which is called for each attribute of the locator. This parameter is optional. If NULL, then all the Gopher attribute information is placed into lpBuffer. If lpfnEnumerator is specified, then the callback function is called once for each attribute of the object. The callback function is passed a pointer to a single GOPHER_ATTRIBUTE_TYPE structure for each call. The enumeration callback allows the application to avoid having to parse the Gopher attribute information.

dwContext

An application-defined value to associate this operation with any application data.

Return Value

If the request is satisfied, a value of TRUE is returned. If not, a value of FALSE is returned. The GetLastError or InternetGetLastResponseInfo functions can be used to retrieve more information about the error.

Remarks

Generally, applications will make this call following a GopherFindFirstFile or InternetFindNextFile call which will then request cached information.

The GOPHER_ATTRIBUTE_ENUMERATOR function has the following syntax:

BOOL GopherAttributeEnumerator(

LPGOPHER_ATTRIBUTE_TYPE lpAttributeInformation,
DWORD dwError
);
The lpAttributeInformation parameter points to a buffer which contains a single GOPHER_ATTRIBUTE_TYPE structure. The lpBuffer parameter to GopherGetAttributes is used for storing this structure. The dwError parameter is NO_ERROR if the attribute was parsed and written to the buffer successfully. If a problem was encountered, an error code is returned. Returning FALSE from this function stops the enumeration immediately.


HTTP Functions

HTTP functions control the quality, quantity, and transmission of HTTP requests.


HttpOpenRequest

The HttpOpenRequest function opens an HTTP request handle.

HINTERNET HttpOpenRequest(

HINTERNET hHttpSession,
LPCTSTR lpszVerb,
LPCTSTR lpszObjectName,
LPCTSTR lpszVersion,
LPCTSTR lpszReferer,
LPCTSTR FAR * lplpszAcceptTypes,
DWORD dwFlags,
DWORD dwContext
);
Parameters

hHttpSession

A handle to an HTTP session returned by InternetConnect.

lpszVerb

The verb to use in the request.

lpszObjectName

The target object of the specified verb. This is generally a filename, an executable module, or a search specifier.

lpszVersion

The HTTP version for the request. The high word defines the minor version and the low word defines the major version. This must be HTTP_VERSION in version 1.0 of the Internet functions for Win32.

lpszReferer

Specifies the address (URI) of the document from which the URI in the request (lpszObjectName) was obtained. This can be NULL. In this case, no referer is specified.

lpszAcceptTypes

Points to a NULL-terminated array of LPCTSTR pointers to content types accepted by the client. This value can be NULL. In this case, no accept types are accepted by the client. Servers interpret a lack of accept types to indicate that the client only accepts documents of type "text/*" (that is, only text documents and not pictures or other binary files).

dwFlags

Any combination of the INTERNET_OPEN_FLAG_* flags. See InternetOpenUrl for further information on INTERNET_OPEN_FLAG_* flags.

dwContext

An application-defined value to associate this operation with any application data.

Return Value

A valid (non-NULL) HTTP request handle is returned, if the function was successful. If not, a NULL value is returned. Extended error information can be retrieved using the GetLastError function.

Remarks

This function creates a new HTTP request handle and stores the specified parameters in that handle.

An HTTP request handle encapsulates a request to be sent to an HTTP server and contains all RFC822/MIME/HTTP headers to be sent as part of the request.

The InternetCloseHandle function is used to close the handle returned by HttpOpenRequest. The InternetCloseHandle cancels all outstanding I/O on the handle.

The lpszCallerApplicationName parameter to InternetOpen is used as the referrer for the HTTP request.

See Also

HttpAddRequestHeaders, HttpQueryInfo, HttpSendRequest, InternetCloseHandle, InternetOpen, InternetReadFile


HttpAddRequestHeaders

The HttpAddRequestHeaders function adds one or more HTTP request headers to the HTTP request handle.

BOOL HttpAddRequestHeaders(

HINTERNET hHttpRequest,
LPCTSTR lpszHeaders,
DWORD dwHeadersLength
);
Parameters

hHttpRequest

An open HTTP request handle returned by HttpOpenRequest.

lpszHeaders

The headers to append to the request. Each header must be terminated by a CR/LF pair.

dwHeadersLength

The length, in characters, of lpszHeaders. If this is -1L, then lpszHeaders is assumed to be zero terminated (ASCIIZ) and the length is computed.

Remarks

This function appends additional "free format" headers to the HTTP request handle and is intended for use by sophisticated clients that need detailed control over the exact request sent to the HTTP server.

Return Value

A value of TRUE is returned, if the function is successful. If not successful, a value of FALSE is returned. Extended error information can be retrieved using the GetLastError function.

See Also

HttpOpenRequest, HttpSendRequest


HttpSendRequest

The HttpSendRequest function sends the specified request to the HTTP server.

BOOL HttpSendRequest(

HINTERNET hHttpRequest,
LPCTSTR lpszHeaders,
DWORD dwHeadersLength,
LPVOID lpOptional,
DWORD dwOptionalLength
);
Parameters

hHttpRequest

An open HTTP request handle returned by HttpOpenRequest.

lpszHeaders

Additional headers to be appended to the request. This can be NULL if there are no additional headers to append.

dwHeadersLength

The length, in characters, of the additional headers. If this is -1L and lpszHeaders is non-NULL, then lpszHeaders is assumed to be zero terminated (ASCIIZ) and the length is calculated.

lpOptional

Any optional data to send immediately after the request headers. This is generally used for POST and PUT operations. This can be NULL if there is no optional data to send.

dwOptionalLength

The length, in bytes, of the optional data. This can be zero if there is no optional data to send.

Remarks

This function sends the specified request to the HTTP server and allows the client to specify additional RFC822/MIME/HTTP headers to send along with the request.

This function also lets the client specify optional data to send to the HTTP server immediately following the request headers. This feature is generally used for "write" operations such as PUT and POST.

After the request is sent, this function reads the status code and response headers from the HTTP server. These headers are maintained internally to the request handle and are available to client applications through the HttpQueryInfo function.

Return Value

If the function is successful, a value of TRUE is returned. If it is not, a value of FALSE is returned.  Extended error information can be retrieved using the GetLastError function.

See Also

HttpOpenRequest, HttpQueryInfo, InternetReadFile


HttpQueryInfo

The HttpQueryInfo function queries information about an HTTP request.

BOOL HttpQueryInfo(

HINTERNET hHttpRequest,
DWORD dwInfoLevel,
LPVOID lpvBuffer,
LPDWORD lpdwBufferLength
);
Parameters

hHttpRequest

An open HTTP request handle returned by HttpOpenRequest.

dwInfoLevel

Indicates the attribute to query.  Each of these query types will return a string of the indicated type, if it exists, from the returned content headers of an HTTP request. The request is identified by a handle. For example, if you queried HTTP_QUERY_CONTENT_TYPE and the content type existed in the received headers, you would receive "text/html."

The possible values include:

HTTP_QUERY_MIME_VERSION
HTTP_QUERY_CONTENT_TYPE
HTTP_QUERY_CONTENT_TRANSFER_ENCODING
HTTP_QUERY_CONTENT_ID
HTTP_QUERY_CONTENT_DESCRIPTION
HTTP_QUERY_CONTENT_LENGTH
HTTP_QUERY_ALLOWED_METHODS
HTTP_QUERY_PUBLIC_METHODS
HTTP_QUERY_DATE
HTTP_QUERY_EXPIRES
HTTP_QUERY_LAST_MODIFIED
HTTP_QUERY_MESSAGE_ID
HTTP_QUERY_URI
HTTP_QUERY_DERIVED_FROM
HTTP_QUERY_LANGUAGE
HTTP_QUERY_COST
HTTP_QUERY_WWW_LINK
HTTP_QUERY_PRAGMA
HTTP_QUERY_VERSION
HTTP_QUERY_STATUS_CODE
HTTP_QUERY_STATUS_TEXT
HTTP_QUERY_RAW_HEADERS
HTTP_QUERY_RAW_HEADERS_CRLF
lpvBuffer

A pointer to the buffer that will receive the information.

lpdwBufferLength

On entry, points to a value containing the length, in bytes, of the data buffer. On exit, points to a value containing the length, in bytes, of the information written to the buffer.

Remarks

Most information levels return simple values. For example, HTTP_QUERY_CONTENT_LENGTH returns an ASCII string representing the size, in bytes, of the returned object.

The HTTP_QUERY_RAW_HEADERS is not so simple. This information level lets a client access the raw RFC822/MIME/HTTP headers returned by the HTTP server. On entry to this funciton, lpBuffer points to the field name of the header to retrieve (for example, Accept). If lpBuffer points to an empty string (for example,  ""), then all headers are returned.

Return Value

A value of TRUE is returned, if the function is successful. If it is not, a value of FALSE is returned. Extended error information can be retrieved using the GetLastError function.

See Also

HttpOpenRequest


Structure Definitions

This list identifies Gopher data structures and their uses.


GOPHER_FIND_DATA

typedef struct {

    TCHAR DisplayString[MAX_GOPHER_DISPLAY_TEXT + 1];

    DWORD GopherType;

    DWORD SizeLow;

    DWORD SizeHigh;

    FILETIME LastModificationTime;

    TCHAR Locator[MAX_GOPHER_LOCATOR_LENGTH + 1];

} GOPHER_FIND_DATA, FAR *LPGOPHER_FIND_DATA;

The GopherFindFirstFile and InternetFindNextFile functions return GOPHER_FIND_DATA structures. The fields of GOPHER_FIND_DATA have the following meanings:

Members

DisplayString

A friendly name that identifies the object. Display this string to the user for selection.

GopherType

A mask of flags which describe the item returned.

FileSizeLow

The low 32 bits of the file size.

FileSizeHigh

The high 32 bits of the file size.

LastModificationTime

The time the file was last modified.

Locator

A locator that identifies the file. Pass this locator to GopherOpenFile or GopherFindFirstFile.

See Also

GopherFindFirstFile


GOPHER_ATTRIBUTE_TYPE

typedef struct {

    DWORD CategoryId

    DWORD AttributeId

    union {

        GOPHER_ADMIN_ATTRIBUTE Admin;

        GOPHER_MOD_DATE_ATTRIBUTE ModDate;

        GOPHER_SCORE_ATTRIBUTE Score;

        GOPHER_SCORE_RANGE_ATTRIBUTE ScoreRange;

        GOPHER_SITE_ATTRIBUTE Site;

        GOPHER_ORGANIZATION_ATTRIBUTE Organization;

        GOPHER_LOCATION_ATTRIBUTE Location;

        GOPHER_GEOGRAPHICAL_LOCATION_ATTRIBUTE GeographicalLocation;

        GOPHER_TIMEZONE_ATTRIBUTE TimeZone;

        GOPHER_PROVIDER_ATTRIBUTE Provider;

        GOPHER_VERSION_ATTRIBUTE Version;

        GOPHER_ABSTRACT_ATTRIBUTE Abstract;

        GOPHER_VIEW_ATTRIBUTE View;

        GOPHER_VERONICA_ATTRIBUTE Veronica;

        GOPHER_ASK_ATTRIBUTE_TYPE Ask;

        GOPHER_UNKNOWN_ATTRIBUTE Unknown;

    } AttributeType;

} GOPHER_ATTRIBUTE_TYPE, *LPGOPHER_ATTRIBUTE_TYPE;

The GOPHER_ATTRIBUTE_TYPE structure contains the relevant information for a single Gopher attribute for an object.

Members

CategoryId

The Gopher name for the attribute.  the possible values include:

GOPHER_CATEGORY_ID_ALL
GOPHER_CATEGORY_ID_INFO
GOPHER_CATEGORY_ID_ADMIN
GOPHER_CATEGORY_ID_VIEWS
GOPHER_CATEGORY_ID_ABSTRACT
GOPHER_CATEGORY_ID_VERONICA
GOPHER_CATEGORY_ID_UNKNOWN
AttributeId

Defines the structure that is contained in the AttributeType member of GOPHER_ATTRIBUTE_TYPE.  The possible values include:

GOPHER_ATTRIBUTE_ID_ADMIN
GOPHER_ATTRIBUTE_ID_MOD_DATE
GOPHER_ATTRIBUTE_ID_TTL
GOPHER_ATTRIBUTE_ID_SCORE
GOPHER_ATTRIBUTE_ID_RANGE
GOPHER_ATTRIBUTE_ID_SITE
GOPHER_ATTRIBUTE_ID_ORG
GOPHER_ATTRIBUTE_ID_LOCATION
GOPHER_ATTRIBUTE_ID_GEOG
GOPHER_ATTRIBUTE_ID_TIMEZONE
GOPHER_ATTRIBUTE_ID_PROVIDER
GOPHER_ATTRIBUTE_ID_VERSION
GOPHER_ATTRIBUTE_ID_ABSTRACT
GOPHER_ATTRIBUTE_ID_VIEW
GOPHER_ATTRIBUTE_ID_TREEWALK
GOPHER_ATTRIBUTE_ID_UNKNOWN
AttributeType

The actual setting for the Gopher attribute. The specific value of AttributeType depends on the dwAttribute member. The definitions of the various attribute structures is available in wininet.h.

See Also

GopherGetAttribute